Compass v2.2
============

Compass is a Nokia showcase example application that demonstrates the use of the
Qt Location API. This application can be used as a traditional compass with
Nokia Maps and it allows the user to determine the bearing to the desired
direction. The tracking function draws the travelled route to the map and the
route can be saved in KML format.

This example application is hosted in Nokia Developer Projects:
- http://projects.developer.nokia.com/compass

For more information on implementation and porting, visit the product�s wiki
pages:
- http://projects.developer.nokia.com/compass/wiki


What's new
----------

The UI of the application has been redesigned and it has been implemented by
using Qt Quick Components.


1. Usage
-------------------------------------------------------------------------------

The application uses QML code as much as possible. Some custom elements are
implemented by using Qt code, such as Arc element to draw the arc-style progress
bar in the calibration view and the PersistentStorage element to allow storing
and retrieving of data to the devices persistent storage.

The walked route is stored in KML file format and it can be opened in many
external map applications.

For more information about the KML file format:
- http://www.opengeospatial.org/standards/kml/


2. Prerequisites
-------------------------------------------------------------------------------

 - Qt basics
 - Qt Quick basics


3. Project structure and implementation
-------------------------------------------------------------------------------

3.1 Folders
-----------

 |                    The root folder contains the license information and this
 |                    file (release notes).
 |
 |- bin               Contains the compiled binaries.
 |
 |- doc               Contains documents and graphics projects that were used
 |                    in development of the application.
 |
 |- src               Contains the project file of the application and Qt/C++
    |                 source code.
    |
    |- icons          Contains application icons.
    |
    |- qml            Root folder for QML and Javascript files.
    |  |
    |  |- common      Common, cross-platform QML and Javascript files.
    |  |
    |  |- harmattan   Harmattan specific QML and Javascript files.
    |  |
    |  |- images      Graphics used in the QML files.
    |  |
    |  |- symbian     Symbian specific QML and Javascript files.
    |
    |- qtc_packaging  Contains the Harmattan (Debian) packaging files.


3.3 Used APIs/QML elements/Qt Quick Components
----------------------------------------------

The application uses the following less commonly used QML elements.

Maps and Navigation API:
- Map
- MapPolyLine
- MapCircle

Gesture handling:
- PinchArea

Mobility:
- Compass
- PositionSource

The Qt Quick Components toolbar is customized in Symbian version; see the code
in src/qml/symbian/CustomToolBar.qml. In the Harmattan version the toolbar is
customized by using ToolBarStyle.


4. Compatibility
-------------------------------------------------------------------------------

 - Symbian devices with Qt 4.7.4 or higher.
 - MeeGo 1.2 Harmattan.

Tested to work on Nokia C7 and Nokia N9 phones. Developed with Qt SDK 1.1.4.

4.1 Required Capabilities
-------------------------

None; the application can be self-signed on Symbian.


4.2 Known Issues
----------------

 - The Map element freezes the UI if the map is panned quickly. This has been
   noticed on Symbian Belle with Nokia 700 and Nokia 701 phones. For more
   information about the bug see 
   https://bugreports.qt.nokia.com/browse/QTMOBILITY-2006.
 

5. Building, installing, and running the application
-------------------------------------------------------------------------------

5.1 Preparations
----------------

Check that you have the latest Qt SDK installed in the development environment
and the latest Qt version on the device.

Qt Quick Components 1.1 or higher is required.

5.2 Using the Qt SDK
--------------------

You can install and run the application on the device by using the Qt SDK.
Open the project in the SDK, set up the correct target (depending on the device
platform), and click the Run button. For more details about this approach,
visit the Qt Getting Started section at Nokia Developer
(http://www.developer.nokia.com/Develop/Qt/Getting_started/).

5.3 Symbian device
------------------

Make sure your device is connected to your computer. Locate the .sis
installation file and open it with Ovi Suite. Accept all requests from Ovi
Suite and the device. Note that you can also install the application by copying
the installation file onto your device and opening it with the Symbian File
Manager application.

After the application is installed, locate the application icon from the
application menu and launch the application by tapping the icon.

5.4 Nokia N9 and Nokia N950
---------------------------

Copy the application Debian package onto the device. Locate the file with the
device and run it; this will install the application. Note that you can also
use the terminal application and install the application by typing the command
'dpkg -i compass_v2_2_harmattan.deb' on the command line. To install the
application using the terminal application, make sure you have the right
privileges to do so (e.g. root access).

Once the application is installed, locate the application icon from the
application menu and launch the application by tapping the icon.


6. License
-------------------------------------------------------------------------------

See the license text file delivered with this project. The license file is also
available online at
- http://projects.developer.nokia.com/compass/browser/Licence.txt


7. Related documentation
-------------------------------------------------------------------------------
Qt Quick Components
- http://doc.qt.nokia.com/qt-components-symbian-1.0/index.html
- http://harmattan-dev.nokia.com/docs/library/html/qt-components/qt-components.html


8. Version history
-------------------------------------------------------------------------------

2.2 Updated the compass graphics.
2.1 Added center icon to better show the current place.
2.0 New UI with Qt Quick Components, added tracking feature.
1.1 Added support for Symbian^1 and MeeGo 1.2 Harmattan.
1.0 Compass data via Qt QCompass.
0.9 Added better graphics. Possibility to disable audio feedback on 
    calibration. Bug fixes. Work-around for QCompass crash by Symbian code.
0.1 First public version in Projects Forum Nokia.

